Customization¶

Panel objects are built on top of Param, which allows Panel objects to declare parameters that a user can flexibly manipulate to control the displayed output. In addition to parameters specific to each component and class of components, all components define a shared set of parameters to control the size and style of the rendered views.

Styling Components¶

css_classes¶

The css_classes parameter allows associating a Panel component with one or more CSS classes. CSS styles can be embedded in raw form or by referencing an external .css file by providing each to the panel extension using the raw_css and css_files arguments; both should be supplied as lists. Outside the notebook or if we want to add some CSS in an external module or library, we can simply append to the pn.config.raw_css and pn.config.js_files config parameters.

To demonstrate this usage, let us define a CSS class called panel-widget-box which we will give a background and a nice border:

Now that we have defined and loaded the CSS we will create a Column with the widget-box CSS class:

background¶

In case we simply want to give the component a background we can define one as a hex string:

loading¶

All components also have a loading parameter which indicates that they are currently processing some event. Setting the parameter will display the global loading_spinner on top of the component. To configure the loading spinner you can set the:

• pn.config.loading_spinner: The style of the global loading indicator, e.g. 'arcs', 'bars', 'dots', 'petals'.
• pn.config.loading_color: The color of the global loading indicator as a hex color, e.g. #6a6a6a

In the notebook these should be configured before loading the pn.extension and may in fact be set using pn.extension(loading_spinner='dots', loading_color='#00aa41').

style¶

Certain components, specifically markup-related panes, expose a style parameter that allows defining CSS styles applying to the HTML container of the pane's contents, e.g. the Markdown pane:

Component Size and Layout¶

The size of components and their spacing is also controlled through a set of parameters shared by all components.

margin¶

The margin parameter can be used to create space around an element defined as the number of pixels at the (top, right, bottom, and left). The margin can be defined in one of three ways:

margin=25
  top, bottom, left, and right margins are 25px

margin=(25, 50)
  top and bottom margins are 25px
  right and left margins are 50px

margin=(25, 50, 75, 100)
  top margin is 25px
  right margin is 50px
  bottom margin is 75px
  left margin is 100px

Absolute sizing using width and height¶

By default all components use either auto-sizing or absolute sizing. Panels will generally take up as much space as the components within them, and text or image-based panes will adjust to the size of their contents. To set a fixed size on a component, it is usually sufficient to set a width or height, but in certain cases setting sizing_mode='fixed' explicitly may also be required.

Plots¶

Unlike other components, the size of a plot is usually determined by the underlying plotting library, so it may be necessary to ensure that you set the size and aspect when declaring the plot.

Responsive sizing¶

By default, panel objects will use a fixed size if one is provided or adapt to the size of the content. However most panel objects also support reactive sizing which adjusts depending on the size of the viewport. These responsive sizing modes can be controlled using the sizing_mode parameter.

sizing_mode¶

• "fixed": Component is not responsive. It will retain its original width and height regardless of any subsequent browser window resize events.

This is usually the default behavior and simply respects the provided width and height.

• "stretch_width": Component will responsively resize to stretch to the available width, without maintaining any aspect ratio. The height of the component depends on the type of the component and may be fixed or fit to component's contents.

To demonstrate this behavior we create a Row with a fixed height and responsive width to fill:

• "stretch_height": Component will responsively resize to stretch to the available height, without maintaining any aspect ratio. The width of the component depends on the type of the component and may be fixed or fit to component's contents.

To demonstrate the filling behavior in a document we declare a Column with a fixed height for the component to fill:

• "stretch_both": Component is completely responsive, independently in width and height, and will occupy all the available horizontal and vertical space, even if this changes the aspect ratio of the component.

To demonstrate this behavior we will declare a Column with a fixed height and responsive width for the component to fill:

• "scale_height": Component will responsively resize to stretch to the available height, while maintaining the original or provided aspect ratio.
• "scale_width": Component will responsively resize to stretch to the available width, while maintaining the original or provided aspect ratio.
• "scale_both": Component will responsively resize to both the available width and height, while maintaining the original or provided aspect ratio.

Spacers¶

Spacers are a very versatile component which makes it easy to put fixed or responsive spacing between objects. Like all other components spacers support both absolute and responsive sizing modes:

VSpacerand HSpacer provide responsive vertical and horizontal spacing, respectively. Using these components we can space objects equidistantly in a layout and allow the empty space to shrink when the browser is resized.